/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/
/* 
This file is the Header for the Dynamic 2D char Array module. The
Dynamic 2D char array is a dynamically allocated array that can be 
indexed using two indexes, like a regular two-dimensional array in C.

=================
1. Example Usage:
=================

	#define HEIGHT 20
	#define WIDTH 10
	int i,j;
	char A[HEIGHT][WIDTH];
	Dynamic2DCharArr B = CreateDynamic2DCharArr( HEIGHT, WIDTH );
	for ( i = 0 ; i < HEIGHT; i++)
		for ( j = 0; j < WIDTH; j++ )
		{
			A[i][j] = 100*i + j;
			B[i][j] = A[i][j];
		}

In the example, the difference between the static 2D array A and the 
Dynamic 2D array is that A's size must be known at compile time.
However, B is Dynamic. In the following example, only B could be used, 
not A:

	unsigned int Height, Width;
	printf("Enter Height and Width of array: ");
	scanf( "%u %u\n", &Height, &Width );
	Dynamic2DCharArr B = CreateDynamic2DCharArr( Height, Width );

Important: Dynamic2DCharArr offers natural indexing, but at a cost:
extra memory needs to be allocated - more than just the memory used to hold
the data. 

This File was written for the course "Introduction
To Systems Programming" at Tel-Aviv University's School of Electrical 
Engineering, Winter 2011, by Amnon Drory.
*/
/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/

#ifndef DYNAMIC_2D_CHAR_ARRAY_H
#define DYNAMIC_2D_CHAR_ARRAY_H

/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/

typedef unsigned char BasicType;
typedef BasicType * LinePtr_Char;
typedef LinePtr_Char * Dynamic2DCharArr;

/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/

/**
 * CreateDynamic2DCharArr allocates memory and created a new 
 * Dynamic 2D Int Array.
 *
 * Parameters:
 * ----------
 * Height - the height of the 2D array to create (number of rows).
 * Width - the width of the 2D array to create (number of columns).
 *
 * Returns:
 * -------
 * NULL - if memory allocation fails.
 * otherwise: a Dynamic2DCharArr object which can be accessed exactly like
 *            a static 2d array of char
 */ 
Dynamic2DCharArr CreateDynamic2DCharArr( unsigned int Height, unsigned int Width );

/**
 * FreeDynamic2DCharArr releases all the memory that was allocated for
 * a Dynamic 2D char Array.
 *
 * Parameters:
 * ----------
 * Arr - the Dynamic 2D char Array whose memory should be released.
 */ 
void FreeDynamic2DCharArr( Dynamic2DCharArr Arr );

/*oOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoOoO*/

#endif // DYNAMIC_2D_CHAR_ARRAY_H